<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
<title>Creating Applications using lispbuilder-SDL-GFX (CFFI bindings for SDL_gfx)</title>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=iso-8859-1" />
<style type="text/css">

body {
margin: 10px 20px 20px 200px;
padding: 0px;
font-family: Verdana, Geneva, Arial, Helvetica, sans-serif;
font-size: small;
text-align: justify;
max-width: 50em;
background-color: white;
}

a, a:visited {
text-decoration: none;
color: maroon;
}

/* index */

div.index {
position: fixed;
top: 0px;
left: 0px;
width: 160px;
height: 100%;
margin: 0px;
padding: 5px;
font-size: 12px;
background-color: #DCDCDC;
border-right: thin black solid;
}

div.index ol {
color: navy;
margin: 0px;
padding-left: 0px;
}

div.index ol li {
list-style: none;
}

div.index ol li:before {
display: marker;
content: counter(heading1) ". ";
counter-increment: heading1;
}

div.index ol ol {
padding-left: 10px;
font-size: 10px;
list-style: none;
counter-reset: heading2;
}

div.index ol ol li:before {
display: marker;
content: counter(heading1)"." counter(heading2)" ";
counter-increment: heading2;
}

/* heading styles */

body > h1 {
margin-top: 0px;
}

h1 {
margin-top: 40px;
margin-bottom: 0px;
color: #4682B4;
}

h1:before {
display: marker;
content: counter(chapter) ". ";
counter-increment: chapter;
counter-reset: section1;
}

h1 + p {
margin-top: 5px;
}

h2 {
margin-top: 20px;
color: #000000;
margin-bottom: 0px;
}

h2:before {
display: marker;
content: counter(chapter) "." counter(section1) "  ";
counter-increment: section1;
}

h2 + p {
margin-top: 0px;
}

h3 {
margin-top: 20px;
color: #000000;
margin-bottom: 0px;
}

h3:before {
display: marker;
content: counter(chapter) "." counter(section1) "." counter(section2) "  ";
counter-increment: section2;
}

h3 + p {
margin-top: 0px;
}

h4 {
margin-top: 20px;
color: #000000;
margin-bottom: 0px;
}

h4:before {
display: marker;
content: counter(chapter) "." counter(section1) "." counter(section2) "." counter(section3) "  ";
counter-increment: section3;
}

h4 + p {
margin-top: 0px;
}

/* generated content for images and tables */

img:after {
content: "[" counter(image) "] " attr(title);
counter-increment: image;
display: block;
font-size: 10px;
font-weight: bold;
margin-top: 5px;
margin-bottom: 20px;
color: black;
}

table:after {
content: "Table " counter(table) ": " attr(summary);
counter-increment: table;
display: table-caption;
caption-side: bottom;
font-size: 10px;
font-weight: bold;
margin-top: 5px;
margin-bottom: 20px;
white-space: nowrap;
color: black;
}

/* code for examples, code and pathnames*/

div.example table {
color: black;
}

div.example, div.code, div.path, div.sequence {
margin: 10px 0px;
border: 1px black solid;
padding: 10px;
background-color: #F4F4F4;
counter-reset: image;
color: maroon;
}

div.example:before {
content: "Example " counter(example);
counter-increment: example;
display: block;
}

div.example + p {
margin-bottom: 0px;
}

div.code:before {
content: "Code";
}

div.path:before {
content: "Path";
}

div.sequence:before {
content: "Sequence";
}

p.reference:before {
display: marker;
content: "[" counter(reference) "]";
counter-increment: reference;
font-weight: bold;
margin-right: 5px;
}

div.code:before, div.example:before, div.path:before, div.sequence:before {
font-weight: bold;
font-size: 15px;
margin-bottom: 20px;
color: black;
}

pre {
color: Green;
margin: 0px;
padding: 0px;
}


/* equation counter */

e:after {
content: "[" counter(equation) "]";
counter-increment: equation;
display: block;
float: right;
margin-right: 10px;
}

/* to prevent the CC image from being numbered */

img[alt="Creative Commons License"] {
display: inline;
}

img[alt="Creative Commons License"]:after {
display: none;
}

div#cc {
background-color: #DCDCDC;
border: thin black solid;
padding: 10px;
font-size: 10px;
}

</style>
</head>

<!--
(CC) 2003 Luke Crook. Some Rights Reserved.
http://creativecommons.org/licenses/by/1.0
This page is licensed under a Creative Commons License.

Maintained by the Common Lisp Application Builder project at www.lispbuilder.org

The entire styleguide was copied wholesale from http://www.markschenk.com/cssexp/publication/article.xml

(CC) 2003 Mark Schenk. Some Rights Reserved.
http://creativecommons.org/licenses/by/1.0
This page is licensed under a Creative Commons License.
-->

<BODY BGCOLOR=#FFFFFF >

<h1 id="lispbuilder-SDL-GFX">lispbuilder-SDL-GFX</h1>

<h2 id="Overview">Overview</h2>
<p><a href="http://www.ferzkopp.net/Software/SDL_gfx-2.0/SDL_gfx">SDL_gfx</a> provides basic drawing routines to be used
on <a href="http://www.libsdl.org">SDL surfaces</a>. As such, SDL_gfx depends on SDL. lispbuilder-sdl-gfx provides the 
bindings and utility functions necessary to integrate SDL_gfx with Common Lisp.</p>
<p>The lispbuilder-sdl-gfx package is a part of the 
<a href="http://www.lispbuilder.org/">Common Lisp Application Builder</a> project which is in turn a part of the 
umbrella <a href="http://www.lispniks.com/cl-gardeners/">Common Lisp Gardeners</a> project.</p>
<p>The purpose of this document is to describe a step-by-step process by which the user may install, configure and
begin using the lispbuilder-sdl-gfx package to create applications using one of the 
<a href="#Implementations">supported Lisp implementations</a>.</p>
<p>The list of credits is contained in <a href="../documentation/CONTRIBUTORS">CONTRIBUTORS</a>. A copy of the license is contained in 
<a href="../documentation/COPYING">COPYING</a>.</p>

<h2 id="Implementations">Supported Implementations</h2>
<p>The following table describes the status of the Lisp implementations that have been tested with lispbuilder-sdl-gfx:</p>

<table border="1" cellpadding="2" cellspacing="0" summary="Supported Implementations"> 
     <tr bgcolor="yellow">
       <td><b>Lisp Implementation</b></td>
       <td colspan="3"><b>lispbuilder-SDL-GFX Status</b></td>
       <td><b>Comments</b></td>
     </tr>	
     <tr bgcolor="yellow">
       <td colspan="1"></td>
       <td><b>Win32</b></td>
       <td><b>Linux</b></td>
       <td><b>MacOS</b></td>
       <td></td></td>
    </tr>
     <tr>
       <td><a href="http://clisp.cons.org/">CLISP v2.38</a></td>
       <td bgcolor="#60c060">Working</td>
      <td bgcolor="#ff6060">Unknown</td>
      <td bgcolor="#ff6060">Unknown</td>
      <td></td>
    </tr>
    <tr>
      <td><a href="http://www.lispworks.com/">Lispworks v2.4.6 Personal</a></td>
      <td bgcolor="#60c060">Working</td>
      <td bgcolor="#ff6060">Unknown</td>
      <td bgcolor="#ff6060">Unknown</td>
      <td>As of [03/30/06], use the 'CFFI-060214' tarball for Windows as more recent versions do not work.</td>
    </tr>
    <tr>
      <td><a href="http://www.franz.com/">Allegro Trial Edition 7.0</a></td>
      <td bgcolor="#ff6060">Unknown</td>
      <td bgcolor="#ff6060">Unknown</td>
      <td bgcolor="#ff6060">Unknown</td>
      <td></td>
    </tr>
    <tr>
      <td><a href="http://openmcl.clozure.com/">OpenMCL</a></td>
      
    <td bgcolor=blue><font color="#FFFFFF">NA</font></td>
      
    <td bgcolor=blue><font color="#FFFFFF">NA</font></td>
      <td bgcolor="#ff6060">Unknown</td>
      <td></td>
    </tr>
    <tr>
      <td><a href="http://www.sbcl.org/">SBCL</a></td>
      
      <td bgcolor=blue><font color="#FFFFFF">When, oh when?</font></td>
      <td bgcolor="#60c060">Working</td>
      <td bgcolor="#ff6060">Unknown</td>
      <td>
      </td>
    </tr>
    <tr>
      <td><a href="http://www.cons.org/cmucl/">CMUCL</a></td>
      
    <td bgcolor=blue><font color="#FFFFFF">When already?</font></td>
      <td bgcolor="#ff6060">Unknown</td>
      
    <td bgcolor=blue><font color="#FFFFFF">NA</font></td>
      <td>
      Justin WIP Debian (sarge)
      </td>
    </tr>
</table>

<h2 id="Prerequisites">Prerequisites</h2>
<p>The packages 
<u><a href="http://cvs.sourceforge.net/viewcvs.py/*checkout*/cclan/asdf/asdf.lisp?rev=1.92">asdf.lisp</a></u>, 
<u><a href="http://common-lisp.net/project/cffi/tarballs/cffi-060225.tar.gz">CFFI</a></u> and 
<u><a href="../../lispbuilder-sdl/documentation/index.html">lispbuilder-sdl</a></u>
must be installed prior to the installation of lispbuilder-SDL. The installation procedures for these pacakges are 
described in the <a href="../../lispbuilder-sdl/documentation/index.html">lispbuilder-sdl documentation</a></u>.</p>

<h2 id="Win32: lispbuilder-sdl-gfx">Installation on Win32 Platforms</h2>

<h3 id="Win32: lispbuilder-sdl-gfx">Installation of lispbuilder-sdl-gfx</h3>
<p>This section describes the installation of the lispbuilder-sdl-gfx package.</p>
<ul>
    <li> download the latest version of the 
    <a href="http://sourceforge.net/project/showfiles.php?group_id=159740">lispbuilder-sdl-gfx</a> 
package from sourceforge and unpack it to the asdf directory, e.g.
    <pre>c:\programme\clisp-2.38\asdf\lispbuilder-sdl-gfx\lispbuilder-sdl-gfx.asd</pre>
    </li>
</ul>

<h3 id="Win32: lispbuilder-sdl and the SDL binary">Installation of the SDL_gfx binary</h3>
<p>This section describes the installation of the SDL_gfx binaries for Windows.</p>
<ul>
  <li> install the SDL_gfx dynamic library by doing <u>one</u> of the following: 
  <ul>
    <li>Download the SDL_gfx-2.0.13.zip package from the 
         <a href="http://www.ferzkopp.net/Software/SDL_gfx-2.0/">official site</a> and 
         copy the SDL_gfx.dll to following system folder:
    <pre>c:\windows\system32</pre>
    </li>
    <li> download the <a href="http://sourceforge.net/project/showfiles.php?group_id=159740&package_id=182505">lispbuilder-sdl-gfx-binaries</a> package from sourceforge and unpack it into the asdf directory, e.g.
    <pre>c:\programme\clisp-2.38\asdf\lispbuilder-sdl-gfx\lispbuilder-sdl-gfx-binaries.asd</pre>
    <pre>c:\programme\clisp-2.38\asdf\lispbuilder-sdl-gfx\bin\SDL_gfx.dll</pre>
    </li>
  </ul>
</ul>

<h2 id="Installation">Installation on Linux Platforms</h2>
<h3 id="Linux: ASDF and CFFI">ASDF and CFFI</h3>
<p>For users of SBCL, OpenMCL, ECL or ACL, ASDF is already installed. Otherwise, Linux users please refer to the official
<a href="http://cvs.sourceforge.net/viewcvs.py/*checkout*/cclan/asdf/README?rev=HEAD&content-type=text/plain">ASDF README</a> for installation instructions.</p>

<h3 id="Linux: lispbuilder-sdl-gfx">Installation of lispbuilder-sdl-gfx</h3>
<p>This section describes the installation of the lispbuilder-sdl-gfx package for Linux users. Download the latest version 
of the <a href="http://sourceforge.net/project/showfiles.php?group_id=159740">lispbuilder-sdl-gfx</a> 
package from sourceforge, and:</p>
<ul>
    <li><u>ASDF-Install</u>: The package is ASDF-Install'able, so install the package using ASDF-install: <code>(asdf-install:install "lispbuilder-sdl_gfx_0.1.tgz")</code>, or</li>
    <li><u>Manual installation</u>: Extract the package to the correct asdf systems directory.
    </li>
</ul>

<h3 id="Linux: The SDL_gfx binary">Installation of the SDL_gfx binary</h3>
<p>This section describes the installation of the SDL_gfx binaries for Linux.</p>
<ul>
  <li>For Fedora Linux:
   <ul>
    <li><u>Application Manager</u>: Download and install the latest SDL_gfx RPMs using the Fedora Application Manager, or</li>
    <li><u>Manual Installation</u>: download and install the SDL_gfx RPMs from the 
       <a href="http://www.ferzkopp.net/Software/SDL_gfx-2.0/">official site.</a>
    </li>
   </ul>
</ul>

<h2>Configuration on Win32 Platforms</h2>

<h3>ASDF Configuration</h3>
<div class="code">
  <p>Add the following to the ASDF *central-registry*:</p>
  <pre>
(pushnew "/programme/clisp-2.38/asdf/lispbuilder-sdl-gfx/" asdf:*central-registry*)
</pre>
  <p>Set "lispbuilder-sdl-gfx_0.1/" to the version number of the lispbuilder-sdl-gfx package, e.g. 
  "lispbuilder-sdl-gfx__{version_number}/".
</div>

<h2 id="Fire it Up">Fire it Up</h2>
<div class="sequence">
 <p>Now  start CLISP and enter the following at the prompt:</p>
<pre>
(load "c:/programme/clisp-2.38/asdf/asdf.lisp")
(asdf:operate 'asdf:load-op :lispbuilder-sdl-gfx-examples)
</pre>

<p>ASDF will take care of loading the CFFI, :lispbuilder-sdl and :lispbuilder-sdl-gfx dependencies. 
The SDL.dll and SDL_gfx.dll libraries will also be loaded into the Lisp image at this time.</p>

<p>Great. If you received any errors during this processes then go back and verify that the pathnames entered into the
*central-registry* match the directories where the packages were installed. Also verify that the SDL.dll and SDL_gfx.dll 
libraries are located somewhere in the search path, as described above.</p>
</div>

<h2 id="Running the included SDL_gfx examples">Running the included SDL_gfx examples</h2>
<div class="example">
<p>To verify that lispbuilder-sdl-gfx is installed correctly, run the example by entering:</p>
<pre>
(sdl-gfx-examples:random-circles)
</pre>

<p>You should see a window like this:</p>
<img src="sdl_gfx1.jpg" width="320" height="253" title="(sdl-gfx-examples:random-circles)" alt="random-circles" />
</div>

</body>
</html>
